This user guide contains a brief and exhaustive description of the components of BroadCast™ and their operation. Brief and exhaustive? Field testing has shown that because the BroadCast system is so easy to use, very little documentation is required. If you don’t agree, please let us know— BroadCast Software Corp. is committed to doing whatever is necessary to make BroadCast and its documentation as accessible as possible.
Introduction
BroadCast is a technology that enables you to distribute and sell software in a large variety of new ways. With this technology, you can make your products available on demand to vast markets that are otherwise too difficult or too costly to reach.
Despite the large number of ways in which BroadCast may be deployed, it is functionally very simple: It locks your software securely, so that it can safely be distributed through publicly accessible media; and it enables you to unlock individual copies of your software remotely. BroadCast is suitable for use by anyone who has experience using your computer operating system— no technical expertise is necessary.
The BroadCast system consists of two components: Locker and KeyMaker. An third component, PatchWorks Lite, is also included, but its use is optional. This user guide shows you how to use the components, and describes the behavior of unlockers (which are created by Locker, and used by your customers).
BroadCast KeyMaker
Description
KeyMaker is the application used by your sales desk personnel to issue passwords to customers. In addition, it allows you to purchase additional passwords whenever your inventory runs low.
KeyMaker’s main window is moveable, and the application’s memory requirement is modest, so you can leave KeyMaker open all the time if you wish. Whenever you need to issue a password to a customer, just bring KeyMaker to the foreground, either by clicking in its window or by choosing it from Finder’s application menu.
Setting up a Product List in KeyMaker
Before you begin using KeyMaker (and before you can build your first unlocker), you must store a list of the products you plan to lock (and for which you plan to issue passwords).
Choose Products from KeyMaker’s File menu. You’ll see a dialog box containing an empty list. Click “Add” to add a product to the list.
Enter a hard-to-guess, unique product code (important since the product code is one element used when generating passwords). Then enter the product name and price. You may also type in descriptive notes. The description you enter is designed to inform your sales personnel of anything they may need to know, or tell customers, or ask customers at the time of a sale.
Click Save. Repeat this for each of your products.
Setting Keymaker’s Preferences
If you elect to accept orders via e-mail, then you will use KeyMaker’s powerful batch processing features to process those orders. When KeyMaker creates e-mail replies to orders, it will (optionally) include some boilerplate text in each reply. The Templates folder in the BroadCast StarterKit contains a file called "Email Reply Boilerplate" which is suitable for editing.
To create an e-mail reply boilerplate file, launch SimpleText (or any other word processing application that can create plain text files). Enter your desired boilerplate, then save the file.
For example:
MegaSoft thanks you for your order.
Be sure to check out our other “UnBoxed” products:
• MegaDraw (4 1/2 Mice)
• MegaCAD
• MegaWord
Please let us know if we can be of any help,
or just call us any time to chat about our products.
Our number is (415) 555-3434.
Choose Preferences from the File menu. There are three preferences you need to set.
KeyMaker maintains an inventory of password points. Whenever you supply a customer with a password, one or more points are deducted, depending on the price of the product that is unlocked. For your convenience, KeyMaker will warn you when your inventory of password points is getting low. Type in a threshold below which you wish to be warned.
KeyMaker keeps track of your password points and products in files that normally reside on your startup disk. However, if you will have multiple sales representatives running KeyMaker on different computers, then you will probably prefer to have a single set of files on a file server. In this way, every KeyMaker user will have access to password points, and will share a single product database.
To select a disk volume other than your startup disk, select a volume from the popup menu. The change will take place immediately.
Click the Email reply button to select your boilerplate file. The text in this file will be inserted whenever KeyMaker builds a reply to an e-mail order.
Issuing Passwords
There are three ways in which you may receive orders to supply a customer with a password:
• Telephone
• Email
• Fax
The decision about which of these is acceptable is yours to make when you lock your software (see BroadCast Locker description, below).
Telephone Orders
When you receive an order by phone, ask the caller if he or she is actually looking at a window containing a “control number.” If not, instruct the caller to run your unlocker, and click the “Unlock Now” button. A window will appear on the caller’s screen containing a unique control number. Ask the caller to read you the control number.
To unlock a customer’s copy of your software, simply type in the customer’s control number, then click on the “Validate” button. Before KeyMaker displays the password required to unlock the customer’s copy of your software, it displays a dialog box requesting that you confirm the control number for accuracy:
Make sure that the product name in this dialog matches the name of the product indicated by the customer. Verbally repeat the control number to your customer, to ensure that the number you type is identical to the number appearing on the customer’s screen. If you’ve made an error, then click “Cancel” and correct your typing.
If you wish to secure an authorization code from your credit card processor before issuing a password over the telephone, then you should do this now.
Once you have confirmed the accuracy of the control number, click on the “Generate Password” button. The password will appear in KeyMaker’s main window.
Read the password to your customer. Instruct the customer to enter it on his or her computer, then to click the “Unlock” button on the screen. You may wish to wait until the unlocking has completed successfully before terminating the telephone call.
Fax Orders
For a fax order, you should get authorization for the customer’s credit card before proceeding. Fax orders will have the control number at the bottom of the orders. To unlock a customer’s copy of your software, simply type in the customer’s control number, then click on the “Validate” button.
Before KeyMaker displays the password required to unlock the customer’s copy of your software, it displays a dialog box requesting that you confirm the control number for accuracy:
Make sure that the product name in this dialog matches the name of the product indicated in the fax order.
Once you have confirmed the accuracy of the control number, click on the “Generate Password” button. The password will appear in KeyMaker’s main window. Record the password, and include it in your reply fax to the customer.
E-mail Orders
KeyMaker has powerful batch processing features to streamline the processing of e-mail orders. These features automate virtually the entire process between the time you receive the orders until you’re ready to send replies. Since each e-mail application stores messages in a proprietary format (including encrypted credit card data), you need to save incoming orders as text files, in order for KeyMaker to process them. You should create a folder on your system for email orders. Whenever you receive orders, save them as text files in that folder.
Although you can process an e-mail order individually (in the same way as you process a phone or fax order), KeyMaker makes it easy to process batches of orders in three easy steps:
1. Choose Decode Email Orders from the File menu. You’ll see an Open File dialog, requesting that you select either a single incoming e-mail order or -- much better -- a folder containing e-mail orders. After making your selection, KeyMaker will quickly process the selected order(s), decoding the encrypted credit card numbers and writing the decoded numbers to the end of the orders. A status dialog tells you how many text files were examined; how many contained orders; and how many were decoded.
2. Print the decoded orders. After dismissing the status dialog, you will see a page setup dialog, followed by a print dialog.
Do not cancel the print dialogs. It is very important to print the decoded orders, because some information will be removed from them in the next step.
Once you have the hard copies, you can obtain authorization for the credit card numbers, and file the printed orders. If a credit card cannot be authorized, then remove the offending order from your orders folder before proceeding to step 3.
3. Choose Reply to Email orders from the File menu. Select either an order or the folder containing orders, as you did before. KeyMaker will process every order that contains a decoded credit card number (or no number, if the product is free). For each order, KeyMaker will do the following:
• Put your boilerplate text at the top of the order (see “KeyMaker Preferences”, above);
• Write a password to the order; and
• Deduct the appropriate number of password points from your inventory.
4. Using your e-mail application, send the replies back to the customers. Note: If you’re sending a message from one internet address to another (or one America Online address to another), then you can simply attach the reply file to your message. If, however, you’re sending a message from the internet to an online service -- or vice-versa, you should copy the reply text to the clipboard, then paste it into the message body.
5. KeyMaker maintains a tab-delimited text file called “KeyMaker Log” which is stored in the BroadCast folder (the folder is in your System folder, or the root directory of the volume on which you store your passwords). This file contains registration information for your new users who ordered via email. If you maintain a database of registered users, you can import the contents of the “KeyMaker Log” file into your database.
Inventory Control
At all times, KeyMaker displays the number of password points you have “in stock.” Each time you issue a password to a customer, your inventory shrinks by one or more points. If your inventory of password points is permitted to fall to zero, then you will be unable to issue passwords to your customers until you have replenished your stock. During high-volume periods, it is possible to run out of password points unexpectedly. To assist you in managing your inventory, KeyMaker can be set to warn you whenever your inventory falls below a certain level.
To set this “red line” level, choose Preferences from KeyMaker’s File menu. Enter a number. From now on, KeyMaker will warn you (with an alert box), whenever your password points inventory falls below this number.
When your password points inventory does get low, you will need to purchase passwords from BroadCast Software Corp. To purchase password points, click on the button in the main window labeled “Order more.” A dialog box will appear. Use the popup menu to select the number of points you need, then click “OK.”
In order to purchase password points, you must either use a credit card, or have deposited payment in advance.
As you might surmise, you acquire password points from BroadCast Software in exactly the same way in which your customers acquire passwords from you. Call BroadCast Software at the number displayed on your screen, and read us the information in the dialog box. Our representative will issue you a password that will automatically increase your inventory of password points by the amount you requested. It’s that simple!
BroadCast Locker
BroadCast Locker is an application that you use to securely lock your software, so that your software can be:
• Safely be distributed through publicly accessible media or channels, and
• Used only by persons who have received authorization from your organization.
Locker can lock either a single file or a folder and its contents (including subfolders and their contents). Regardless of whether you lock a file or a folder and its contents, Locker always creates a single locked application program, called an Unlocker.
When your customer wants to unlock your software, he simply launches the Unlocker, and is presented with a dialog box containing instructions, and affording several ordering options. One option, if you accept telephone orders, is “Unlock Now.” The customer sees a “control number,” and calls you to receive an unlocking password based on that control number. Other options allow the customer to order via e-mail or fax, then await the return of a password by the same medium. If the password is correct, the Unlocker recreates whatever you locked - either a file or a folder and its contents.
Note: Every time a user launches your Unlocker, a unique control number is displayed. Therefore, the password required by the Unlocker is always unique as well: The password you provide to that user will not work for a different user, nor even for the same user at another time.
Tip: If your product is large, and you plan to distribute the Unlocker electronically via modem (or if space is tight on your distribution disk), you may wish to use BroadCast’s integrated file compression. This feature can significantly reduce the size of Unlockers, while further enhancing their security. Note that the degree of compression will vary, depending on the nature of the files you are locking. Applications and other binary code can be reduced modestly in size, while other kinds of files will yield dramatic compression ratios.
Using BroadCast Locker consists of filling out several dialog boxes:
• Enter information about your company
• Enter information about the object you wish to lock
• Choose among options for controlling the behavior of the Unlocker
• Type instructions intended for the end user; and
• Build the Unlocker
Publisher Information
Enter your company name, telephone number (if you plan to accept phone orders), fax number (if you plan to accept fax orders), and e-mail address(es) (if you plan to accept e-mail orders).
Indicate which credit cards you accept by checking the appropriate boxes.
Indicate how you wish to accept orders, by checking the appropriate boxes.
Product Information
Click “Select file or folder” to identify the object you want to lock.
Click “Save unlocker as” to determine where the Unlocker will be saved, and what it will be called.
Pick the corresponding product information by using the popup menu to select the correct product code (from the product database you created using KeyMaker).
If your product does not appear on the popup menu, then Locker either cannot locate the correct KeyMaker “BroadCast Products” file. KeyMaker stores the “BroadCast Products” file in the BroadCast folder (the folder is in your System folder, or the root directory of the volume on which you store your passwords). Simply copy the “BroadCast Products” file to the BroadCast folder (in the System folder) of the computer that you’re running Locker from.
Locker Options
If you have an attractive picture that you wish to appear in the unlocker, then identify it by clicking “Select logo picture.” If the size of the picture exceeds 113 by 113 pixels, then it will be scaled down to that size. If the picture is smaller than 113 by 113, then it will be centered in a square area in the Unlocker’s main screen. The "templates" folder in the BroadCast StarterKit contains a file called "Unlocker PICT Template" which is suitable for editing.
If you wish to minimize the size of the Unlocker, check “Compress while unlocking.” For large objects, you will probably achieve better compression by building an uncompressed unlocker, then compressing it with a commercial compression utility. Alternatively, you could first create a self-extracting archive, then use Locker to lock the archive.
If you wish to limit the useful life of the Unlocker, click the “Expires” radio button, and enter a values in the days field. The Unlocker will expire that many days after the modification date of the object you are locking. This feature gives you the opportunity to ensure that Unlockers you may have posted long ago don’t come back to haunt you after you’ve replaced them with newer versions. When end-users launch an expired Unlocker, an alert informs them that it has expired, displays your telephone number, and suggests that they call you for the latest version.
Use the SmartLaunch popup menu to determine what will happen to the Unlocker, and how “special objects” will be handled by the Unlocker. Special objects include self-extracting archives created by StuffIt Deluxe or CompactPro, and converter applications created by PatchWorks Pro.
If the object you are locking is a special object, and if you choose “Yes” from the menu, then the Unlocker will behave as follows:
• The object will be unlocked
• The unlocked application will be launched
• Both the Unlocker and the unlocked application will be moved to the user’s trash.
This provides a one-step operation for your customers, who need not concern themselves with the extra steps of updating or extracting. Regardless of the nature of the unlocked object, your menu selection will determine whether theUnlocker itself is moved to the trash.
Personalizing/Serializing your Software (hidden feature). The templates folder in the BroadCast StarterKit contains a file called “BroadCast Personalization.r” which contains a “virgin” personalization resource (type = 'pAtP', ID = 5678). Before locking your software, use ResEdit to paste the virgin personalization resource into your software. When your software is later unlocked, the Unlocker will write personalization information to the 'pAtP' resource for your software’s use. The resource will contain three Pascal strings, occupying 64 bytes each. Your software can use the controlNumber string as a unique serial number. If the user ordered via email or fax, then the customerName and customerCompany strings will contain the user’s name and company name, respectively. Here is the structure of the completed 'pAtP' resource:
typedef struct
{
Str63 controlNumber;
Str63 customerName;
Str63 customerCompany;
}
Type end-user instructions
This important step allows you to compose instructions that will appear to the end-user when the unlocker is launched. We have provided a template for those instructions for your convenience, but you can delete this text and compose your own if you prefer.
Locker allows you to enter styled text, so your instructions will have an attractive appearance and greater impact. You can style the text in just the same way as would using a word processor: Select a range of text, then use the menus to choose font, style, size, and color attributes for the selected text. Or, if you prefer, you can prepare instructions in SimpleText, then either paste the text into this screen, or choose Open from the File menu to retrieve the prepared text You can also save the instructions to a text file (for later use) by choosing Save from the File menu.
Note: The fonts you choose are not stored in the unlocker that will be created. When choosing fonts, be sure to use “standard” fonts that are certain to reside on your customers’ computers. When choosing sizes, use “standard” sizes for bitmap fonts, so the end-user will not see unsightly “jaggies” as a result of scaling. If you know that the end user’s font is a True Type font, then scaling poses no problem.
Build the Unlocker
Once you are satisfied with your choices and instructions, click “Build” to create the Unlocker.
BroadCast Unlockers
Unlockers that you create using Locker are intended for use only by your prospective customers. Still, once you have built an Unlocker, you will want to test and become familiar with it.
When an unlocker is launched, the user sees a dialog box like this one:
After reading the instructions, the user can click “Help” for more information.
The customer has one or two options, depending upon your choices when you built the unlocker.
If You Accept Phone Orders
The user can click “Unlock Now” and
• call your sales desk;
• supply your representative with name, address, credit card information (if applicable), etc.;
• read the displayed control number to your representative;
• and enter the password given by your representative.
The user enters the password, then clicks on the “Unlock” button. The Unlocker quickly reconstructs, on the user’s hard disk, whatever you locked (i.e., either a file or a folder and its contents) when you built the Unlocker. If you do not accept phone orders, then only one button will be visible, and it will lead to an order form dialog.
If You Accept E-mail or Fax Orders
The user can click “Unlock later” and
• complete an order form,
• click the “E-mail order” or “Fax order” button to save the order on the desktop,
• send the order to you via e-mail or fax.
The state of the “E-mail order” and “Fax order” buttons is also determined by those choices: If you did not allow fax orders, for example, then that button will be hidden, and the user will not be required to enter his fax number.
The credit card popup menu will allow the user to choose among only those cards accepted by your company.
If the object you locked is free, then the fields pertaining to credit cards will be hidden.
PatchWorks Lite
PatchWorks Lite is an optional component of the BroadCast suite of applications. It has only one function: to create converter documents that can convert demo versions of your software to live versions.
Why convert a demo to a live version? If your software is unusually large, and you plan to distribute unlockers on the internet or online services, then prospective customers may be discouraged from downloading both a demo and a locked live version of your software. By exploiting the technology in PatchWorks Lite, you can post a package containing:
• A demo version (with e-docs), and
• A locked converter— which is much smaller than your live version,
because it contains only the differences between the demo and live versions.
When a customer unlocks a converter, the unlocker will apply the converter to the customer’s demo copy, and quickly convert it to the live version.
PatchWorks Lite allows a developer to create an converter literally in minutes. Since no programming is required, no bugs are introduced.
What PatchWorks Lite Can Do
PatchWorks Lite is suitable for virtually all programs: applications, system extensions (INITs), control panels (cdevs), and so on. Converters can be built for 68K programs, native PowerPC programs, fat binary programs, and applications created by other development systems, such as 4D.
There is only one restriction: The file to be converted must have a valid 'vers' resource. Although Apple specifies that this resource should have an ID of 1, PatchWorks Lite will recognize a 'vers' resource with any ID.
Using PatchWorks Lite
When you launch PatchWorks Lite, its only window appears: As indicated by the dark horizontal lines, the window is divided into three parts.
Old File
This section determines which demo file will be processed by PatchWorks Lite. The “Demo version” button invokes a Open File dialog. Just select the demo copy of your software.
New Files
The “Live version” button invokes a Open File dialog. Just select the live copy of your software. The “Converter” button invokes a Save File dialog that lets you specify a name and location for the converter that will be created.
While building an converter, PatchWorks Lite records its activity in a log file, which can be perused using SimpleText or any word processor. The “Log” button invokes a Save File dialog that lets you specify a name and location for this log file. If you choose not to specify a log file, then no log will be created.
Screen name
If you want the end user to see a file name other than the actual name of the demo then choose “Specify” from the popup menu, and enter a name. Otherwise, the name that appears to the user will be the actual name of the Demo.
File Menu
For your convenience, all the settings you choose may be saved in a settings document, and loaded any time. Once you have filled out the settings in the main window, you should choose “Save settings as…” in order to save time in subsequent sessions. Of course, you can document-launch PatchWorks Lite by opening a settings document.
Choose “Build converter” from the File menu (or click the Build button) when you’re satisfied with your choices. A dialog will show you the progress as PatchWorks Lite creates a converter.
BroadCast Usage and Technical Notes
1. BroadCast Locker and BroadCast KeyMaker require System 7.0 or later. However, the unlockers you build will operate correctly under System 6.0.5 or later, with one exception: The “SmartLaunch” features function only if the end-user is running System 7.0 or later.
2. BroadCast KeyMaker creates and maintains a folder named “BroadCast Folder” in your System folder (or on the volume you chose from KeyMaker’s Preferences window). It is essential that you neither delete, nor move, nor alter the files in this folder in any way.
3. You can use either the Macintosh or Windows versions of KeyMaker to generate passwords for both Macintosh and Windows Unlockers.
4. If you use BroadCast Locker to lock a folder and its contents (as opposed to a single file), be sure that the folder contains no aliases. Locker will ignore any aliases it may find.
5. BroadCast Locker uses a modified Huffman encoding algorithm to achieve file compression. The effectiveness of this algorithm is robust across many types of files. However, it sometimes cannot equal the compression ratios realized by commercial compression utilities, which apply one of several algorithms to each file, depending on its contents. If minimizing the size of your unlockers is of utmost importance, you may wish to use a commercial compression utility to create a self-extracting archive (SEA), then use Locker (with its compression disabled) to lock the SEA. Alternatively, you could build an uncompressed Unlocker, then use a commercial compression utility to lcompress the Unlocker.
6. When BroadCast Locker builds an unlocker, it installs a System 7 custom icon in the unlocker. If you prefer the unlocker to bear your own icon, just use Finder’s Get Info box to copy and paste your own icon into the unlocker. In either case, the custom icon will not be displayed on computers running System 6.
7. If an Unlocker is launched from a read-only disk volume (e.g., a CD-ROM), then the end user will we prompted (with a Save File dialog) to save the unlocked item(s) on another volume. Also, once a product has been unlocked, the Unlocker will not be deleted from a read-only volume, since it is not possible to do so.
8. The password points in your KeyMaker inventory are commodities for which you have paid, and which, once used, cannot be recovered. In order to protect your investment, BroadCast Software Corp. has incorporated code into unlockers that enable your customers to recover from unforeseen system failures without having to request a new password from you. For example, if a customer should experience a system crash, disk I/O error, or power outage while the unlocker is operating, he will not require a new password for a subsequent attempt to unlock your software.
9. File Type Visibility in PatchWorks Lite. When you click “Demo version” or “Live version”, the Open File dialog displays only files having certain types. If the file for which you want to build an converter does not appear, it’s because the file’s type is not included in PatchWorks Lite’s default list of file types. You can add file types to the default list easily using a resource editor. The types are stored in STR# resource ID 131. No more than 64 file types should be present in STR# resource 131. Similarly, you may remove types from this list if you do not want them to be displayed.
